json: copy the text between two escapes in bulk - #47720

What the diff touches

• src/parsers/json_stage2.rs only: +184 lines of production code, none removed. The diff has four hunks and each one only adds lines.
• No hunk is inside decode_string_escapes, read_trail_surrogate_escape or push_codepoint. The old parse_string_slow keeps its body under the name parse_string_by_code_point. It runs when a string of the document has a control character.
• No unsafe, no new public item, no change outside this crate.

How a string is decoded now

1. If stage 1 saw a control character in a string, the old function runs. Such a document is an error.
2. text_len finds the first backslash. A string with none is returned as it is, as before.
3. A row of escapes at the start of the string is decoded first. A string such as "\n" is done here.
4. utf8_len gives the length of the UTF-8 text at the start of the string. A string of 64 bytes or less is checked without a call to simdutf.
5. Up to that length, the text between two escapes is copied in one step.
6. From the first byte that is not UTF-8, or from the first bad escape, decode_string_escapes decodes the rest into the same buffer. It logs an error at the place of the string, not at a place inside it, so the message and its position do not change.

Measurements

Linux x64, EPYC with AVX-512, release builds of the merge base and of this branch. Instructions and cycles are user-space counts for the process. Cycles and milliseconds are from interleaved runs, with the range beside the median.

One printed error (Bun.inspect(error)) through a bundle built with bun build --target=bun --sourcemap=external:

bun bench/json-corpus/escaped-strings.mjs writes 26 documents. Instructions per Bun.JSONC.parse, in millions:

• The none document has no string that reaches this code. Its count moves by 0.7% from run to run on one build.
• parse_object and parse_array have 1654 and 881 instructions in both builds. In each, only the addresses of ten constants differ.

Three documents hold bytes that are not UTF-8. A string from JavaScript cannot carry them, so they are measured through an import of a .jsonc file, three runs each:

The first two are lower by 0.1%. The third cannot be told apart from main.

Other vector widths. The x64 binary holds kernels for 16, 32 and 64-byte vectors and selects one at run time. I measured copies of both binaries limited to AVX2 and to SSE4, with simdutf forced to haswell and westmere: 29 documents at each width. No document is above main by more than the 0.7% run-to-run noise. The three documents that are not UTF-8 are within 0.1% of main at both widths. No arm64 machine was available, so arm64 is not measured.

Instructions for one call of parse_string_slow, counted with a debugger in the steady state:

"é\n" is equal: one instruction is not a gain. So a string of one character that is not ASCII and one escape is not faster.

Other callers, instructions for the whole process:

• The installs use a registry on localhost that serves the real abbreviated manifests, a fresh cache and no lockfile.
• In those four manifests every backslash is inside a dist["npm-signature"] value: 47,696 of 47,696 for typescript. 1,630 of its 3,872 versions have that field. So the gain is for a resolve that fetches manifests with such versions.

Size and memory:

• Text size: 140,286,972 to 140,292,860 bytes, +5,888.
• test/bundler/compile-aot-size.test.ts counts the bytes that a bun build --compile --aot executable of a hello world maps. At the merge base: 68,121,572, and 25,961,444 with --trim. With this PR: 68,138,020 and 25,965,604. The bound of that test for --trim is 25,880,000 and only goes down, so the test fails at the merge base too, and this PR adds 4,160 bytes to that.
• Peak RSS of one parse: no change that the measurement can show. Over documents of 1,000 to 64,000 short strings the difference is between -0.5 MB and +0.4 MB, with no trend, and one measurement varies by 0.5 MB or more. For one 1 MB string it is about 1 MB lower (main 3.7 to 4.3 MB, this PR 2.7 to 3.2 MB over four runs), because the buffer is reserved once.

Why the search has three steps

text_len reads four bytes with a branch each, then words of 8 bytes, then calls the Highway kernel when 64 bytes or more are left.

• The branches. I built a variant that reads words from the first byte. With one byte between two escapes it needs 4.90 M cycles per parse of one-byte-runs. Main needs 4.48 M and this PR 3.06 M (minimum of 7 interleaved runs). A word makes each step wait for the load of the step before it. The branches cost something too: with four to six bytes between escapes the variant is 6 to 8% lower in cycles, and on source-lines it is 11% lower in instructions. Both are far below main on those documents.
• The words. index_of_char reads input of less than 16 bytes one byte at a time: 62 instructions for 9 bytes, measured. A word reads 8 bytes in one step.
• The kernel from 64 bytes. On SSE4 and AVX2 the kernel scans what is left after its last whole vector one byte at a time (HWY_MEM_OPS_MIGHT_FAULT in vendor/highway). With 64 bytes or more it reads whole vectors first on every x64 target.
• This is a deviation from a rule. src/CLAUDE.md says that a byte search must go through bun_core::strings, and the branches and the words do not. The source lint does not match their form, so it does not show this.
• I measured the form that follows the rule: text_len as one call to strings::index_of_char_usize at every length. Its unit tests pass. In instructions it is below main on the 19 documents that I measured. In cycles it is above main on two (minimum of 7 interleaved runs). With one byte between two escapes it needs 7.60 M per parse, main 4.43 M and this PR 3.19 M. With two bytes it needs 5.76 M, main 4.78 M and this PR 3.07 M. For long text it equals this PR: source-lines takes 1.99 M against 2.13 M.
• Two other ways to reduce the deviation are not measured: the four branches followed by the helper with no word loop, and the handling of short input inside strings::index_of_char_usize for all of its callers. The second is a change to shared code with its own measurements. A maintainer can choose.

Tests

• test/js/bun/jsonc/jsonc.test.ts: three tests. The first compares Bun.JSONC.parse with JSON.parse for 7,920 strings: six kinds of text at 24 lengths around 4, 12, 64 and 76 bytes, with 11 escapes in five places, and strings of 4095, 4096 and 9000 characters. The second checks the exact message of 2,676 documents that must be rejected. Some have the escape in another string, after a comment or a single quote. Those pin the flag that stage 1 sets for a control character, in both of its indexers. The third reads 199 escapes through both decoders: alone, where the bulk decoder runs, and before a string with a line break, where the code point decoder runs. Both must take the same escapes, so a change to one of the two tables alone fails in CI. It checks the decoded value for the bulk decoder. For the other one it can only see if the escape was taken.
• json-differential-fuzz.test.ts: a chunk of 7 to 150 equal characters, so the seeded fuzz reaches text longer than a word.
• test/js/bun/resolve/jsonc.test.ts and test/bundler/bundler_loader.test.ts: bytes that are not UTF-8 in strings with an escape, through a .jsonc import and through the JSON loader of bun build. They pin the repair that the old loop makes.
• All of these pass on main too. They pin what must not change.
• I changed results by hand to check that the two new tests can fail: one wrong character in a batch of 330 strings, a long string one character short, a missing value, a wrong key, a valid document in the rejection table, a wrong message. Each one fails the test and names the string.
• Under the debug build with ASAN the two large tests take 0.7 to 1.0 s each over ten runs, and the third about 0.14 s. The strings are built with Buffer.alloc, as test/CLAUDE.md asks. For these lengths it is not faster than repeat: four interleaved runs of each form overlap.
• 27 test files pass under the debug build with ASAN: the five above with json-test-suite, then json5 (2 files), inspect-error, the source map tests of test/js/bun/sourcemap (5), test/js/node/module (3), inspect-inline-sourcemap, bun-build-compile-sourcemap, bundler_env, bundler_bun, bundler_edgecase, bun-pm-pkg, coverage, cli/run/env, regression 22003 and the two source map tests of test/bake/dev.
• The source lints pass with a release build: 195 of 195. Under the debug build two of them that scan the whole tree reach the 5 s limit.
• Six unit tests in json_stage2.rs compare the new path with decode_string_escapes for about 700,000 generated string bodies, through the parser and directly. CI type-checks the unit tests of bun_parsers and no lane runs them. scripts/bench-json-rust.sh --test does not link on main. I ran them with bench-json-rust.sh: link the real Highway kernels, compiled as C++23 #46070 applied: 45 of 45 pass.
• Bun.JSONC.parse gives the same value or the same error as main for 14,456 JSON files (440 M characters): every .json, .jsonc and .map file of the repository, the manifests above and the corpus.

The review of my first version

I first wrote a decoder that also repaired text that is not UTF-8 in bulk. A review of it raised ten points.

• Addressed (6): three kinds of text were above main. A measured alternative was smaller, and lower on 11 of the 15 documents I had then. This PR builds on it. The comments. The rejection tests, their messages and the long strings. The test through the bundler.
• No longer apply (3): a buffer of its own for a long string raised peak RSS, and left a dead function and a new unsafe block. This PR has no such buffer and does not touch src/ast/e.rs. Tests for --define values: that decoder is not changed.
• Not taken (1): the unit tests of bun_parsers in the cargo test lane. It needs a choice between the real kernels and stand-ins for that crate's tests. That is a change of its own.

Not in this PR

• Lexer::decode_escape_sequences (src/js_parser/lexer.rs:422), scan_basic_string (src/parsers/toml.rs:1224) and scan_double_quoted_scalar (src/parsers/yaml.rs:5420) decode escapes in their own loops.
• text_len stays private to this file. It has one caller.
• The old loop calls memmove twice for each character of three bytes: 160 calls of length 3 for 80 CJK characters. One call is in push_codepoint. I did not find where the other is. I tried four forms of push_codepoint and each one made some text slower than main, so this PR leaves it as it is.
• A lookup still reads and indexes the whole map for each printed error. jsc: keep the code frame of a printed error for the next print of the same place #47659 keeps the frame of a printed error for the next print of the same place.